home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / dlink.doc < prev    next >
Text File  |  1994-02-13  |  11KB  |  273 lines
  1.  
  2. dlink/dlink                             dlink/dlink
  3.  
  4.                   DLINK.DOC
  5.  
  6.     DLINK <options> <files> <libraries>
  7.  
  8.     Options may occur anywhere on the command lines.  Any file ending in
  9.     .o[bj] is assumed to be an object file.  Any file ending in .l[ib] is
  10.     assumed to be a library.  Any file name beginning with @ specifies a
  11.     text file containing a further list of files.
  12.  
  13.     File ordering is maintained.  Section ordering is maintained.  All
  14.     sections of the same name are coagulated together with ordering
  15.     maintained.  EXCEPTION: inter-section ordering is not maintained
  16.     within a library since library modules are random included.  However,
  17.     ordering is maintained *between* libraries.
  18.  
  19.     All object files specified are included in the final executable.  All
  20.     libraries specified are searched at the point they are specified (that is,
  21.     specifying an object file that references a symbol defined in a library
  22.     specified BEFORE the object file will cause an undefined symbol error).
  23.     Normally an object file is specified after a library to terminate an
  24.     autoinit or autoexit section.
  25.  
  26.     You do not have to order object files within a library, DLink will
  27.     automatically make as many passes as required to handle all internal
  28.     library references.  However, ordering object files will make DLink go
  29.     faster.
  30.  
  31.     Symbols defined in object files overide symbols defined in libraries.
  32.     Symbols defined in libraries specified before later libraries overide
  33.     symbols defined in later libraries.  Symbols defined in a library and
  34.     also defined in a later specified object module causes an error.
  35.  
  36.                 CREATING A LIBRARY
  37.  
  38.     DLink libraries are standard Amiga libraries... simply join one or more
  39.     object modules together and rename the result with a .lib extension.
  40.  
  41.              LINKER SYMBOLS AND A4 RELATIVE ADDRESSING
  42.  
  43.     DLink generates the following special symbols to aid in program
  44.     startup:
  45.  
  46.     __ABSOLUTE_BAS  base of data in volatile space.  This symbol is NOT
  47.             defined for normal residentable programs since the
  48.             base address is not known (must be allocated run-time)
  49.  
  50.     __DATA_BAS        base of data in non-volatile space.  This symbol points
  51.             to a read-only copy of the initialized data for a
  52.             program.  For Non-residentable programs this is the
  53.             same as __ABSOLUTE_BAS.
  54.  
  55.             For residentable programs this points to a read-only
  56.             copy of the initialized data that the program can
  57.             duplicate on startup.
  58.  
  59.             For programs linked with an absolute base address for
  60.             data this points to the end of the CODE section.  The
  61.             ROMABLE program always generates a ROM copy of the
  62.             initialized data just after the CODE section (which
  63.             startup code must copy into RAM)
  64.  
  65.     __DATA_LEN        Length of data space is LONGWORDS.    I.E. __DATA_LEN * 4
  66.             yields the number of bytes of initialized data.  This
  67.             is used by startup code to copy read-only initialized
  68.             data to volatile space (residentable and data-absolute
  69.             programs)
  70.  
  71.     __BSS_LEN        Length of bss space in LONGWORDS.  I.E. __BSS_LEN * 4
  72.             yields the number of bytes of uninitialized (BSS) data.
  73.             This is used in combination with __DATA_LEN to allocate
  74.             the DATA+BSS space for residentable programs, and clear
  75.             the BSS space for non-residentable and absolute-
  76.             data-base programs.
  77.  
  78.             The BSS space occurs after the DATA space unless the
  79.             -frag option is used.
  80.  
  81.     __RESIDENT        This symbol is set to 0 if the -r option was used and
  82.             1 if the -r option was not used.  If set to 1 (-r
  83.             option), then NO BSS SPACE IS PREALLOCATED WHEN THE
  84.             PROGRAM IS RUN.  The startup code must allocate DATA+BSS
  85.             space, copy read-only initialized data over to this
  86.             space, and clear out the BSS portion before it the
  87.             program can run.
  88.  
  89.             Programs linked with the -mw or -ma options obviously
  90.             do not 'allocate' their data space since it is
  91.             predefined.  Most Amiga programmers will never use
  92.             the -mw or -ma options, by the way.
  93.  
  94.  
  95.                 SMALL DATA MODEL
  96.  
  97.     The small data model uses A4 relative addressing.  The linker sets up
  98.     all relative offsets such that A4 must be initialized by startup code
  99.     the BaseOfInitializedData + 32766 for A4-relative references to access
  100.     the appropriate address.
  101.  
  102.                     RESIDENT
  103.  
  104.     If the -r options is given then NO BSS SPACE is allocated after the
  105.     data space... the startup code MUST allocate a data+bss space as shown
  106.     above.  DLink will give error messages for any absolute data references
  107.     that occur (except the __DATA_BAS symbol which must be used to copy the
  108.     static data to the newly allocated data+bss memory on program startup).
  109.  
  110.     DLink will give an error message if any data-data reloco32s exist when
  111.     you specify the -r option as such relocations would be incorrect when
  112.     copied to the newly allocated data+bss space.  DC1 understands this and
  113.     will produce autoinit code to handle any such static data relocations
  114.     that occur in your C code when the -r option is given to compile a C
  115.     program.
  116.  
  117.     However, DLink does allow data-data relocations to occur if an absolute
  118.     data base is specified along with the -r option.  This is used only
  119.     when making ROMABLE code.
  120.  
  121.                    PC-RELATIVE
  122.  
  123.     Because the linker will insert a jump table for PC-RELATIVE references
  124.     to different hunks (after coagulation) or where the range is larger
  125.     than +/-32K, data should not be placed into a code segment and be
  126.     referenced via an external label(pc) unless you are positive the
  127.     reference is within +/-32K.  This can only happen when referencing
  128.     between like-named code hunks.  NOTE that the jump table is tagged
  129.     onto the end of the section the jump(s) occur in and thus you do
  130.     not want to have any autoinit/autoexit code that might possibly
  131.     generate a jump table (since the whole idea with autoinit is that
  132.     the code falls through to other autoinit code until the terminating
  133.     section in x.o's RTS).
  134.  
  135.     Currently dlink cannot handle inter-module PC-RELATIVE references
  136.     beyond +/-32K (i.e. when one object file has more than 32K of code).
  137.     An error will occur.
  138.  
  139.     Note that if -frag is used you cannot make PC-RELATIVE calls
  140.     between sections of differing names ever, or make a program resident.
  141.     The -frag option is almost never used on untested.
  142.  
  143.                 OVERLAYS (NOT SUPPORTED)
  144.  
  145.     Overlays are not supported as yet.
  146.  
  147.                      OPTIONS
  148.  
  149.     Options:
  150.  
  151.     -o execname     name of executable
  152.  
  153.     -s            Include symbolic information.  NOTE, if -r is used
  154.             symbolic info for the data sections will point to
  155.             the statically init'd stuff, NOT The actual data
  156.             space (in BSS) referenced by the code.  This is a bug.
  157.  
  158.     -frag        Fragment output file (default is to coagulate all
  159.             hunks of the same type regardless of name).  If
  160.             frag is specified then only hunks of the same type
  161.             AND name are coagulated.
  162.  
  163.             see fragmentation note at bottom
  164.  
  165.     -r[es]        Resident link.
  166.  
  167.     -pi         Position independant non-residentable (i.e. only
  168.             one copy of the data but also no relocation hunks)
  169.  
  170.     -pr         residentable position independant
  171.  
  172.     -P<postfix>     specify library name postfix.  If DLink cannot find
  173.             the library as specified it will append the postfix
  174.             and try again.    Used by DCC to specify the memory
  175.             model.
  176.  
  177.     -mw addr        specify absolute data base
  178.     -ma addr        specify absolute data base
  179.  
  180.             Both options do exactly the same thing and are in
  181.             duplicate to conform to DCC's options.
  182.  
  183.             -mw/-ma specify the base of data as a decimal,
  184.             0octal, or 0xHEX address.  You must use the -r
  185.             option in conjunction with these options.
  186.  
  187.             DLink will resolve all Absolute-Word addresses
  188.             but not all Absolute-Long addresses.  This is left
  189.             up to the ROMABLE program which generates a raw
  190.             binary image of the program that can then be
  191.             transfered to an EPROM.
  192.  
  193.             DO NOT USE WHEN GENERATING AMIGA EXECUTABLES
  194.  
  195.     -d[#]        debug mode (spews lots of debugging junk out)
  196.  
  197.     -E file        specify stderr file, any errors are appended to the file
  198.             instead of to stdout.  Useful for batch compiles
  199.  
  200.     -chip        chip-only - forces all hunks into CHIP memory
  201.  
  202.     -L0         remove default library search path, including all
  203.             explicitly specified (-L dir) directories up to
  204.             this point.
  205.  
  206.     -L dir        add the specified directory to the library search
  207.             path.  If the object module or library can not be
  208.             found in the current directory, directories
  209.             specified with -L are searched.  -L directories are
  210.             searched before the default library directory
  211.             (DLIB:), assuming it was not removed with -L0 .
  212.  
  213.             Note that the directory path specified by -L is used to
  214.             search for libraries AND object modules.
  215.  
  216.             A trailing '/' is optional
  217.  
  218.     -P<postfix>     This allows you to specify -lc -Ps and DLink will
  219.             automatically look for cs.lib ... you can specify a
  220.             postfix that occurs before the '.lib' in the
  221.             library name here.  If DLink cannot find the
  222.             library as it is named by default it will try
  223.             it with the postfix.
  224.  
  225.             DCC uses this to supply the memory model to DLINK
  226.             also allowing the user to say '-lm' in DCC and have
  227.             it find MS.LIB if you are using the small-data
  228.             model.
  229.  
  230.  
  231.             SPECIAL NOTE ON FRAGMENTATION
  232.  
  233.     When -frag is specified, the linker will not create a special
  234.     combined data+bss hunk (so data and bss can both be referenced with
  235.     one base variable).
  236.  
  237.     However, when -frag is NOT specified, the linker will stil not
  238.     necessarily combine ALL data hunks into one big hunk and ALL bss
  239.     hunks into one big hunk.  Any data or bss hunk with special upper
  240.     bits set (e.g. to force it into chip) is not combined into these
  241.     special hunks, and any data or bss hunk whos NAME begins with
  242.     'far' (upper or lower case) will also not be considered.
  243.  
  244.                 EXAMPLE
  245.  
  246.     This is what DCC gives the linker to link the program 'foo.c' :
  247.  
  248. dlink dlib:c.o @tmp dlib:x.o -o ram:foo
  249.  
  250. --- tmp ---
  251. foo.o
  252. dlib:c.lib dlib:amiga.lib dlib:auto.lib
  253. -----------
  254.  
  255.     Basically it tells dlink to link the startup code, c.o, then the
  256.     program object module(s) (foo.o), then c.lib, amiga.lib, and auto.lib,
  257.     then finally x.o.
  258.  
  259.     DCC handles all this for you
  260.  
  261.     auto.lib contains autoinit code for certain selected libraries,
  262.     including the dos.library.    Autoinit code is brought in whenever a
  263.     given library base symbol has been referenced BUT NOT DEFINED. auto.lib
  264.     defines the symbol and generates autoinit code to open the library and
  265.     autoexit code to close the library.  To maintain portability you
  266.     probably do not want to use this automatic library-openning feature
  267.     yourself, it is really meant to support certain actions of the DICE
  268.     library (such as floating point support).
  269.  
  270.     x.o terminates the autoinit and autoexit sections with an RTS. The
  271.     autoinit and autoexit sections are called from the startup code c.o .
  272.  
  273.